Decision Nodes

Structure

Decisions are stored as structured JSON, organized by scope. Each decision captures what was decided, why, and what constraints follow from it.

{
  "id": "ui-001",
  "scope": "UI",
  "decision": "Use Tailwind CSS for all styling",
  "status": "active",
  "rationale": "Consistent design tokens, easy for AI to generate correct classes.",
  "constraints": [
    "No arbitrary values (e.g. w-[37px]) unless absolutely necessary",
    "Use @apply only for reusable base components"
  ],
  "createdAt": "2024-03-20T10:00:00Z"
}

Fields

Fields marked (optional) can be left blank when adding a decision.

• id ui-001, backend-003, api-012Auto-generated from the scope name (first 10 lowercase letters) + incrementing 3-digit number. For global decisions, displayed with a global: prefix (e.g. global:ui-001).
• scope UI, Backend, API, Architecture, SecurityThe architectural domain this decision belongs to. Scopes are normalized to title case (ui, UI, Ui all become Ui). Each scope becomes its own JSON file on disk (e.g. ui.json, backend.json).
• decisionA clear, actionable statement of what was decided. One sentence. e.g. "Use Tailwind CSS for all styling."
• rationale(optional) The why. Explains the trade-offs considered. This is what prevents the AI from suggesting alternatives that violate your reasoning.
• constraints(optional) Specific rules that must be followed. e.g. "No arbitrary values like w-[37px]." The AI reads these as hard requirements.
• status active | deprecatedAlways active when created. Use decide deprecate <id> to deprecate and decide activate <id> to re-activate. Only active decisions appear in semantic search results.

Storage

Each scope is stored as a JSON file wrapping an array of decisions:

// ~/.decisionnode/.decisions/MyProject/ui.json
{
  "scope": "UI",
  "decisions": [
    { "id": "ui-001", "scope": "UI", "decision": "...", ... },
    { "id": "ui-002", "scope": "UI", "decision": "...", ... }
  ]
}

~/.decisionnode/.decisions/
  _global/                    # Global decisions (shared across all projects)
    ui.json
    vectors.json
  MyProject/
    ui.json                   # UI scope decisions
    backend.json              # Backend scope decisions
    vectors.json              # Embedding vectors for semantic search
    history/
      activity.json           # Audit log

Lifecycle

Decisions are either active or deprecated:

# Deprecate a decision (hides from search)
decide deprecate ui-001

# Re-activate it later
decide activate ui-001

Deprecating is a softer alternative to deleting — the decision is hidden from search and invisible to the AI, but you can bring it back with decide activate if you change your mind. The vector embedding is kept, so re-activating is instant with no need to re-embed. The AI can also deprecate/activate decisions through the MCP update_decision tool when you ask it to.